AI 시대의 소프트웨어 프로젝트 문서화

소프트웨어 프로젝트 문서화를 어떻게 해야할까에 대한 고민.

목적

에이전트와 인간 모두 읽기 좋은 문서를 만들어서 누구나 시스템을 빠르게 이해하고 일관된 규칙을 따르도록 돕는다.

원칙

문서를 코드처럼 관리한다.

중복을 제거하고 의도가 간결하고 명확하게 드러나게 한다.
응집력이 높은 단위의 문서로 나누고 좋은 이름을 지어준다.
문서 간 링크를 걸어서 연결하되 순환참조를 줄이고 엔트리로부터의 내비게이션 경로가 너무 길어지지 않도록 한다.
죽은 문서(엔트리로부터 도달 불가능한 문서)는 삭제한다.
자동으로 생성할 수 있는 문서는 버전 관리를 하지 않는다.

보편 디자인을 지향한다.

에이전트용 문서와 인간용 문서를 되도록 하나로 관리한다.
에이전트 전용 또는 인간 전용 문서는 필요한 경우에만 예외적으로 나눈다.

독자(에이전트+인간)가 충분히 똑똑하다고 가정한다.

필요한 정보가 주어지면 올바른 판단을 할 것이라고 가정한다. 예: “X를 하려면 Y를 읽으세요”라는 지시 보다는 Y에 어떤 내용이 담겨 있는지를 설명해서 X를 할때 Y를 읽어야 하는지 여부는 독자가 판단하도록 한다.

DOs and DON’Ts:

❌ 당연한 내용(예: 코드를 깔끔하게 작성한다)은 쓰지 않는다.
✅ 당연하지 않은 결정사항들(예: tailwind를 쓰지 않는다, mock object를 쓰지 않는다 등)을 명시한다.
❌ 현재 시스템의 문제점을 덮기 위한 용도로 쓰지 않는다.
✅ 문서화에 대한 문서를 만든다. (“문서를 코드처럼 관리한다”에서 자연스럽게 도출)

의사결정에 필요한 정보를 충분히 제공한다(좀 더 고민+구체화 필요):

기획 및 비즈니스 관련 문서도 점진적으로 버전 관리를 한다.
깃헙, 노션, 구글 드라이브, 슬랙 등을 목적에 맞게 사용한다?
흩어진 정보를 쉽게 참고할 수 있게 한다?
사용하는 도구를 줄인다?
흩어진 정보를 점진적으로 통합한다?

실천

README.md는 최대한 짧게 줄인다.

# Project name

This project uses [AGENTS.md](./AGENTS.md) as the entry document.

Claude Code가 AGENTS.md 표준을 지원하기 전까지 한시적으로 AGENTS.md에 대한 심볼릭 링크 CLAUDE.md를 만들어 둔다.

AGENTS.md에는 반드시 LLM 컨텍스트에 담겨야 할 최소한의 내용만 담고 나머지는 모두 Dynamic context discovery 패턴을 쓴다. 다음은 예시:

# Project name

Short description of the project

## Essentials

...essential information that must always be included in the context...

## Documents

- System architecture and project structure: [docs/architecture.md](docs/architecture.md)
- General coding standard: [docs/coding.md](docs/coding.md)
- Additional coding standard for test cases: [docs/testing.md](docs/testing.md)
- Additional coding standard for SQL: [docs/sql.md](docs/sql.md)
- Documentation standard: [docs/metadoc.md](docs/metadoc.md)
- ...

각 스킬 내의 문서들도 마찬가지로 해당 스킬에 특화된 내용만 남기고 중복된 내용은 공통 문서를 링크한다.

목적

원칙

실천

See also